\documentclass[a4paper,twoside]{report}

\newcommand{\mvtbyear}{2018}

\usepackage{times}
\usepackage{graphicx}
\usepackage{wrapfig}
\usepackage{pdfpages}
\usepackage{hyperref}
\usepackage{fancyhdr}
\usepackage[overlay]{textpos}
\usepackage{mathptmx}
\usepackage{anyfontsize}
\usepackage{longtable}
\usepackage{t1enc}
\hypersetup{
  colorlinks=true,
  linkcolor=black
  }
  
\def\topfraction{.9}
\def\bottomfraction{.9}
\def\textfraction{.1}
\def\floatpagefraction{.9}

\setlength{\parindent}{0mm}
\usepackage{parskip}
\usepackage{color}
\usepackage{sectsty}
\allsectionsfont{\sffamily}
\makeatletter
\newcommand\funcsection{%
\@startsection{section}{1}{\z@}%
  {-3.5ex \@plus -1ex \@minus -.2ex}%
  {2.3ex \@plus.2ex}%
  {\color{red}\sffamily\huge\bfseries}}
\makeatother

\input{release.tex}

%\usepackage{multind}
\usepackage{multicol}

% printindex stuff

\makeatletter
\def\printindex#1#2{\subsection*{#2}
  \@input{#1.ind}}
  
\def\theindex{\parindent\z@
\parskip\z@ plus .3pt\relax\let\item\@idxitem}
\def\@idxitem{\par\hangindent 40pt}
\def\subitem{\par\hangindent 40pt \hspace*{20pt}}
\def\subsubitem{\par\hangindent 40pt \hspace*{30pt}}
\def\endtheindex{}
\def\indexspace{\par \vskip 10pt plus 5pt minus 3pt\relax}
\makeatother

\usepackage{fancyvrb}
\fvset{formatcom=\color{blue},fontseries=c,fontfamily=courier,xleftmargin=4mm,commentchar=!}
\DefineVerbatimEnvironment{Code}{Verbatim}{formatcom=\color{blue},fontseries=c,fontfamily=courier,fontsize=\footnotesize,xleftmargin=4mm,commentchar=!}

\pagestyle{empty}

\def\Mlab{MATLAB}

\begin{document}
\setlength{\TPHorizModule}{1cm}
\setlength{\TPVertModule}{1cm}

%%%%%%%%%%%%%%%%% TITLE PAGE
\begin{textblock}{19}(-3.0,-4.5)
\includepdf{titlepage}
\fontsize{75}{80}\selectfont
\textbf{Machine Vision}\\[5pt]
\textbf{Toolbox}\\[5pt]
\fontsize{40}{45}\selectfont
for MATLAB\textsuperscript{\textregistered}\\[5pt]
Release 4

\vspace*{18cm}
\hfill\textbf{Peter Corke}\\[5pt]
\end{textblock}
\thispagestyle{empty}
\newpage
%%%%%%%%%%%%%%%%% INSIDE FRONT COVER
\vspace*{\fill}
\begin{tabular}{ll}
Release & \release \\
Release date & \reldate \\[20pt]
Licence & LGPL \\
Toolbox home page &  \url{http://www.petercorke.com/robot} \\
Discussion group & \url{http://groups.google.com.au/group/robotics-tool-box}
\end{tabular}
\vspace*{\fill}
\hrule
Copyright \textcopyright \mvtbyear Peter Corke\\
peter.i.corke$@$gmail.com\\
\url{http://www.petercorke.com}
\vspace*{\fill}
\setlength{\fboxsep}{10pt}%

%%%%%%%%%%%%%%%% CONTENT
\pagestyle{headings}        % Gives page headings at top of page
\lfoot{Machine Vision Toolbox \release\ for \Mlab\textsuperscript{\textregistered}}
\rfoot{Copyright \copyright Peter Corke \mvtbyear}

\setcounter{section}{0}
\addcontentsline{toc}{section}{Preface}
\chapter*{Preface}
\pagestyle{fancyplain}
\begin{wrapfigure}{l}{4cm}
\vspace{-2ex}\includegraphics[width=3.5cm]{figs/frontcover.pdf}
\end{wrapfigure}
This, the fourth major release of the Toolbox, representing nearly twenty years of continuous
development.
This version corresponds to the \textbf{second edition} of the book ``\textit{Robotics, Vision \& Control, second edition}'' published in 2017.

The Machine Vision Toolbox (MVTB) provides many 
functions that 
are useful in machine vision and vision-based control.
It is a somewhat eclectic collection reflecting my personal interest in
areas of photometry, photogrammetry, colorimetry.
It includes over 100 functions spanning operations such as
image file reading and writing, acquisition, display, filtering,
blob, point and line feature extraction,  mathematical morphology, 
homographies, visual Jacobians,
camera calibration and color space conversion.
The Toolbox, combined with \Mlab\ and a modern PC
is a useful and convenient environment for investigation of machine
vision algorithms.  For modest image sizes the processing rate can
be sufficiently ``real-time'' to allow for closed-loop control.  
%Focus of
%attention methods such as dynamic windowing (not provided) can be
%used to increase the processing rate.
%With input from a firewire or web camera (support provided) and 
%output to a robot
%(not provided) it would be possible to implement a visual servo system
%entirely in \Mlab.

An image is usually treated as a rectangular array of pixel values -- the natural datatype for \Mlab -- representing
intensity or perhaps range.
Many image operations such as thresholding, filtering and statistics can
be achieved with existing \Mlab\ functions.
The Toolbox extends this core functionality with M-files that
implement functions and classes, and mex-files for some compute
intensive operations.
%It is possible to use mex-files to interface with image acquisition
%hardware ranging from simple framegrabbers to robots.
%Examples for firewire cameras under Linux are provided.
This toolbox predates all of the relevant Mathwork's Toolboxes including Image Processing 
Toolbox\textsuperscript{\textregistered} (IPT) and Computer Vision System Toolbox\textsuperscript{\textregistered} (CVST).
MVTB is less complete than these products but  is open-source.

The code is written in a straightforward manner which allows
for easy understanding, perhaps at the expense of computational efficiency.
If you feel strongly about computational efficiency then you can always
rewrite the function to be more efficient,
compile the M-file using the \Mlab\   compiler, or
create a MEX version.

The bulk of this manual is auto-generated from the comments in the \Mlab\ code itself.
For elaboration on the underlying principles, extensive illustrations and worked examples please consult
 ``\textit{Robotics, Vision \& Control, second edition}''  which provides a detailed discussion (720 pages, nearly 500 figures and over 1000 code examples) of how to use the Toolbox functions to solve many types of problems in robotics.


\newpage
\tableofcontents
\newpage
\chapter*{Functions by category}
\addcontentsline{toc}{section}{Functions by category}
\begin{multicols}{2}
\IfFileExists{funcidx_body.tex}{\input{funcidx_body.tex}}{} 
\end{multicols}
\newpage
\chapter{Introduction}
\section{Changes in MVTB 4}
MVTB 4 is largely backward compatible with MVTB 3.

\subsection{Incompatible changes}
\begin{itemize}
\item \texttt{xycolorspace} replaced with \texttt{showcolorspace('xy')}.  It can also display Lab colorspace.
\item \texttt{iconv} changed to \texttt{iconvolve}
\item \texttt{solar.dat} has the units changed from $\mathrm{W/m^2/nm}$ to $\mathrm{W/m^2/m}$.
\item \texttt{RegionFeature} property \texttt{shape} has been renamed to  \texttt{aspect}
\item Data files that were previously in the folder \texttt{private} but are now in \texttt{data}.
\item Options of the form \texttt{'Tcam'}, \texttt{'Tobj'}, \texttt{'T0'} or \texttt{'Tf'} are now respectively 
\texttt{'pose'}, \texttt{'objpose'}, \texttt{'pose0'} or \texttt{'posef'}.
\end{itemize}

%\subsection{Compatible changes}
%\begin{itemize}
%\end{itemize}

\subsection{New features}
\begin{itemize}
\item For a vector of \texttt{RegionFeature} objects all the properties can now be extracted as vectors.
\item Bundle adjustment is supported by the new \texttt{BundleAdjust} class.
\item The folder \texttt{symbolic} contains Live Scripts that demonstrate use of the MATLAB Symbolic Math Toolbox\textsuperscript{TM}
for deriving Jacobians related to bundle adjustment, image Jacobian for visual servoing and Gaussian kernels.
\end{itemize}

\subsection{Enhancements}
\begin{itemize}
\item cmf2xyz for spectral input multiplies by $\Delta \lambda$
\item color data
\end{itemize}

\section{How to obtain the Toolbox}
The Machine Vision Toolbox is freely available from the Toolbox home
page at 
\begin{quote}
\url{http://www.petercorke.com}
\end{quote}

%The web page requests some information from you
%regarding such as your country, type of organization and application.
%This is just a means for me to gauge interest and to remind myself
%that this is a worthwhile activity.

The file is available in \Mlab toolbox format (\texttt{.mltbx}) or zip format (\texttt{.zip}). 

\subsection{From .mltbx file}
Since MATLAB R2014b toolboxes can be packaged as, and installed from, files with the extension \texttt{.mltbx}. Download the most recent version of \texttt{robot.mltbx} or \texttt{vision.mltbx} to your computer. Using MATLAB navigate to the folder where you downloaded the file and double-click it (or right-click then select Install). The Toolbox will be installed within the local MATLAB file structure, and the paths will be appropriately configured for this, and future MATLAB sessions.

\subsection{From .zip file}
Download the most recent version of robot.zip or vision.zip to your computer. Use your favourite unarchiving tool to unzip the files that you downloaded.
To add the Toolboxes to your MATLAB path execute the command
\begin{verbatim}
  >> addpath RVCDIR ;
  >> startup_rvc
\end{verbatim}
where \texttt{RVCDIR} is the full pathname of the folder where the folder \texttt{rvctools} was created when you unzipped the Toolbox files. The script \texttt{startup\_rvc} adds various subfolders to your path and displays the version of the Toolboxes.
After installation the files for both Toolboxes reside in a top-level folder called \texttt{rvctools} and beneath this are a number of folders:

\begin{tabular}{ll}
\texttt{robot} & The Robotics Toolbox \\
\texttt{vision} & The Machine Vision Toolbox\\
\texttt{common} & Utility functions common to the Robotics and Machine Vision Toolboxes\\
\texttt{simulink}  & Simulink blocks for robotics and vision, as well as examples \\
\texttt{contrib} & Code written by third-parties\\
\end{tabular}


A menu-driven demonstration can be invoked by 
\begin{verbatim}
  >> mvtbdemo
\end{verbatim}

The MVTB distribution includes the code and example images necessary to do almost all the examples in the Robotics, Vision \& Control
book.  Additional files are available:
\begin{itemize}
\item \texttt{contrib.zip} A small number of Toolbox functions depend on third party code which is included in this file. Please note and respect the licence conditions associated with these packages.
Those functions are: 
\texttt{igraphseg},
\texttt{imser}, and
\texttt{CentralCamera.estpose}.
\item \texttt{contrib2.zip} Additional third party code for
the functions: \texttt{isift}, and \texttt{isurf}.
Note that the code here is slightly modified version of the open-source
packages.
\item \texttt{images2.zip} This is a large file (150MB) containing the mosaic, campus, bridge-l and campus sequences which support the examples in Sections 14.6, 14.7 and 14.8 respectively.
\end{itemize}

If you already have the Robotics Toolbox installed then download
the zip file(s) to the directory above the existing \texttt{rvctools} directory
and then unzip them.
The files from these zip archives will properly interleave with the Robotics
Toolbox files.

Ensure that the folder \texttt{rvctools} is on your \Mlab\ search
path.  You can do this by issuing the \texttt{addpath} command at 
the \Mlab\ prompt.
Then issue the command \texttt{startup\_rvc} and it will add a number
of paths to your \Mlab\ search path.
You need to setup the path every time you start \Mlab\ but you can 
automate this by setting up environment variables, editing your 
\texttt{startup.m} script by pressing the ``Update Toolbox Path
Cache" button under \Mlab\ General preferences.

\subsection{MEX files and IPT substitution}
The Toolbox comes with MEX files for fast computation of image labelling (\texttt{ilabel}), mathematical morphology (\texttt{imorph}) and other less commonly used operations.  Binaries for Windows, Linux and Mac are shipped for most functions. 

If the MEX files are not available for your platform then you can compile them. Change into the \texttt{mex} folder and follow the instructions in the README file.  You will need to have a C compiler.  You can build the MEX files from inside MATLAB using \texttt{make.m} or from the command line using \texttt{make}.

If you  have the MATLAB Image Processing Toolbox (IPT) installed then the following MVTB functions will use IPT functions instead of MEX files: \texttt{imorph}, \texttt{idilate}, \texttt{ierode}, \texttt{ilabel}. 

\subsection{MATLAB Online\textsuperscript{TM}}
The Toolbox works well with MATLAB Online\textsuperscript{TM} which lets you access a \Mlab\ session from a web browser, tablet 
or even a phone.
The key is to get the MVTB files into the filesystem associated with your Online account.  The easiest way to do this is to install
MATLAB Drive\textsuperscript{TM} from MATLAB File Exchange or using the Get Add-Ons option from the MATLAB GUI.  This functions
just like Google Drive or Dropbox, a local filesystem on your computer is synchronized with your MATLAB Online account.  Copy the MVTB
files into the local MATLAB Drive cache and they will soon be synchronized, invoke \texttt{startup\_rvc} to setup the paths and you are ready to machine vision on your mobile device or in a web browser.

MATLAB Online does not support MEX files.  If you have IPT as part of your MATLAB Online licence then the Toolbox will use that functionality to support key functions such as: \texttt{imorph}, \texttt{idilate}, \texttt{ierode}, \texttt{ilabel}. 


\subsection{Simulink\textsuperscript{\textregistered}}
Simulink\textsuperscript{\textregistered} is the block diagram simulation environment for MATLAB.
The following Simulink models are included with the Toolbox, but rely on having RTB installed.

\begin{center}
\begin{tabular}{|l|l|}\hline
\multicolumn{2}{|l|}{General} \\\hline
\texttt{sl\_ibvs} & Classical IBVS \\
\texttt{sl\_partitioned} &  XY/Z partioned IBVS \\\hline\hline
\multicolumn{2}{|l|}{Robot manipulator arm} \\\hline
\texttt{sl\_arm\_ibvs} &  Servo a 6DOF robot arm\\\hline\hline
\multicolumn{2}{|l|}{Mobile ground robot} \\\hline
\texttt{sl\_drivepose\_vs} &  Drive nonholonomic robot to a pose\\
\texttt{sl\_mobile\_vs} &  Drive a holonomic vehicle to a pose\\\hline\hline
\multicolumn{2}{|l|}{Flying robot} \\\hline
\texttt{sl\_quadrotor\_vs} &  Control visual servoing to a target\\ \hline
\end{tabular}
\end{center}


\subsection{Documentation}
This document {\tt vision.pdf} is a comprehensive manual that describes all functions in the Toolbox.
It is auto-generated from the comments in the \Mlab\ code and is fully hyperlinked:
to external web sites, the table of content to functions, and the ``See also'' functions
to each other.

The same documentation is available online in
alphabetical order at \url{http://www.petercorke.com/MVTB/r4/html/index_alpha.html}
or by category at \url{http://www.petercorke.com/MVTB/r4/html/index.html}.
Documentation is also available via the \Mlab\ help browser,  under supplemental software, as ``Machine Vision
Toolbox".


\section{Compatible MATLAB versions}
The Toolbox has been tested under R2016b and R2017aPRE.  Compatibility problems are increasingly likely the older your version of \Mlab\ is.

\section{Use in teaching}
This is definitely encouraged!
You are free to put the PDF manual (\texttt{robot.pdf} or the web-based documentation {\texttt{html/*.html} on a server for class
use.
If you plan to distribute paper copies of the PDF manual then every copy must include the first two pages (cover and licence).

Link to other resources such as MOOCs or the Robot Academy can be found at \url{www.petercorke.com/moocs}.

\section{Use in research}
If the Toolbox helps you in your endeavours then I'd appreciate you citing the Toolbox when you publish.
The details are:
\begin{verbatim}
@book{Corke17a,
    Author = {Peter I. Corke},
    Note = {ISBN 978-3-319-54413-7},
    Edition = {Second},
    Publisher = {Springer},
    Title = {Robotics, Vision \& Control: Fundamental Algorithms in {MATLAB}},
    Year = {2017}}
\end{verbatim}
or
\begin{quote}
P.I. Corke, Robotics, Vision \& Control: Fundamental Algorithms in MATLAB. Second edition. Springer, 2017. ISBN 978-3-319-54413-7.
\end{quote}
which is also given in electronic form in the CITATION file.

\section{Support}
There is no support!  This software is made freely available in the hope that you find it useful in solving whatever problems
you have to hand.
I am happy to correspond with people who have found genuine
bugs or deficiencies but my response time can be long and I can't guarantee that I respond to your email.

\textbf{I can guarantee that I will not respond to any requests for help with assignments or homework, no matter
how urgent or important they might be to you.  That's what your teachers, tutors, lecturers and professors are paid to do.}

You might instead like to communicate with other users via 
the Google Group called ``Robotics and Machine Vision Toolbox'' 
\begin{quote}
\url{http://tiny.cc/rvcforum}
\end{quote}
which is a forum for discussion.
You need to signup in order to post, and the signup process is moderated by me so allow a few
days for this to happen.  I need you to write a few words about why you want to join the list
so I can distinguish you from a spammer or a web-bot.

\section{Related software}
\subsection{Image Processing Toolbox}
The Image Processing Toolbox\textsuperscript{TM} (IPT) from MathWorks is an official and supported product. 
This toolbox includes a comprehensive set of image processing operations.

\subsection{Computer Vision System Toolbox}
The Computer Vision System Toolbox\textsuperscript{TM} (CVST) from MathWorks is an official and supported product.  System toolboxes (see also the Computer Vision System Toolbox) are aimed at developers of systems. 
This toolbox includes a comprehensive set of feature detectors and descriptors, and be used with Simulink to conveniently generate machine vision
pipelines that can run in target hardware.

\subsection{Octave}
GNU Octave (www.octave.org) is an impressive piece of free software that implements a language that is close to, but not the same as, \Mlab. 

\subsection{Robotics Toolbox}
Robotics toolbox (RTB) for {\Mlab} provides a very wide range of useful robotics functions and is used to illustrate principals in the Robotics, Vision \& Control book.  You can obtain this from \url{http://www.petercorke.com/robot}.


\section{Acknowledgements}
This release includes functions for computing image plane homographies and
the fundamental matrix, contributed by Nuno Alexandre Cid Martins of 
I.S.R., Coimbra.
RANSAC code by Peter Kovesi;
pose estimation by
Francesco Moreno-Noguer, Vincent Lepetit, Pascal Fua at the CVLab-EPFL;
color space conversions by Pascal Getreuer;
numerical routines for geometric vision by various members of the Visual Geometry Group at Oxford (from the web site of
the Hartley and Zisserman book\footnote{\url{http://www.robots.ox.ac.uk/~vgg/hzbook}};
the k-means and MSER algorithms by Andrea Vedaldi and Brian Fulkerson;the graph-based image segmentation software by Pedro Felzenszwalb;
and the SURF feature detector by Dirk-Jan Kroon at U. Twente.
The Camera Calibration Toolbox by Jean-Yves Bouguet is used unmodified.Functions such as SURF, MSER, graph-based segmentation and pose estimation are based on great code 
Some of the MEX file use some really neat macros that were part of the package VISTA Copyright 1993, 1994 University of British Columbia.
See the file \texttt{CONTRIB} for details.



\renewcommand{\section}{\funcsection}
%\setcounter{secnumdepth}{-1}
%\settocdepth{section}
\newpage
\chapter{Functions and classes}
\IfFileExists{all.tex}{\input{all.tex}}{} 

\bibliographystyle{ieeetr}
\bibliography{strings,robot,control,dynamics,kinematics,force,grind,publist,software}
\end{document}
